/*
 * Copyright 2004 original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.jbfilter.bean;

import java.util.Collection;
import java.util.LinkedList;
import java.util.List;

import org.jbfilter.core.FilterComponent;

/**
 * Completes the {@link FilterComponent} contract for JVM side filtering (in memory filtering).
 * @author Marcus Adrian
 * @param <E> for type safety the filter component must be parameterized with the type of the beans to filter.
 */
public interface FilterComponentBean<E> extends FilterComponent<E> {
	/**
	 * Filtering out the passed in collection of beans, that means
	 * removing those beans which don't pass the {@link #pass(Object)} method.
	 * <p>
	 * Because of eventually numerous removing operations, for performance reasons
	 * a {@link LinkedList} is expected as the passed in collection of beans.
	 * @param coll the collection of beans
	 */
	void filterOut(LinkedList<E> coll);
	/**
	 * Filters the collection.
	 * <p>
	 * The original collection passed in as a parameter is NOT modified.
	 * Instead a new collection (a list) of the elements which passed the filter is returned.
	 * Returning a list ensures that ordering will be preserved if the passed in collection was
	 * ordered.
	 * If the {@link FilterComponentBeanSpecific} is disabled the returned collection will contain the same
	 * elements as the passed in collection.
	 * 
	 * Note that this method is the same as creating a {@link FilterBean}, attaching one {@link FilterComponentBeanSpecific}
	 * and call {@link FilterBean#filter(Collection)}. Thus avoiding to create a filter if there is only a single
	 * {@link FilterComponentBeanSpecific}.
	 * @param toFilter the collection to filter
	 * @return the elements which passed the filter
	 */
	List<E> filter(Collection<E> toFilter);
	/**
	 * Indicates if this single bean passes whatever the filter component is testing with this method.
	 * @param bean the bean to test
	 * @return  {@code true} if the bean passes , otherwise {@code false}.
	 */
	boolean pass(E bean);
}
